Skip to main content

Duo Security

Cisco Duo is a data security solution designed to protect online identities through features such as Multi-Factor Authentication (MFA). Pia has integrated with Duo to support Partners using Duo Security as their primary authenticator.

Important

For partners using Duo Security, Pia has developed two automation workflows - Challenge User Identity via Duo and Manage User’s MFA.

To use these automations, a Duo integration must be configured.

Duo issues unique API keys for each client. Therefore, a custom integration is required so that you can securely store and manage separate configuration values for each client individually.

Automations​

Challenge User Identity via Duo

With the Duo Integration, you can authenticate your clients using Duo before processing with their request. This helps the engineers to authenticate any user they are sceptical about and adds one more medium to authenticate apart from Microsoft.


Example request workflow

  1. Client calls the engineer to reset their password.
  2. Engineer runs the Challenge User Identity automation or the extension package before running the Reset Network Password automation.
  3. The automation triggers a push notification in the client's Duo mobile app.
  4. Client is able to authenticate themselves by approving the request.
  5. Engineer proceeds with the Password Reset request.
Chatbot view:

Manage MFA Users for Duo

The Manage MFA Users for Duo automation allows Partners to manage the users that have signed up for Duo Authentication. It provides the following solutions:

  • Modify User Details
  • Associate Phone to User
  • Send Enrolment Email
  • Manage Phones

Example request workflow

  1. Client submits a request to remove a number from Duo.
  2. Engineer runs the Manage MFA Users for Duo automation in the chatbot.
  3. The automation will remove the selected phone as an MFA method for the user.
Chatbot view:

Obtaining the API Credentials from Duo​

Follow the steps on this document to obtain API credentials from Duo: https://duo.com/docs/adminapi

A short process is included below, however please be aware that the vendor application may change and you would be best to consult the vendor documentation for this information.
  1. Sign up for a Duo Account
  2. Log in to the Duo Admin Panel and navigate to Applications → Application Catalog.
  3. Locate the entry for Admin API in the catalog. Click the + Add button to create the application, and get your integration key, secret key, and API hostname.
  4. Pia requires the following Permissions on the API for this integration:
    • Grant resource - Read
    • Grant resource - Write
  5. Optionally specify which IP addresses or ranges are allowed to use this Admin API application in Networks for API Access

Integration Setup​

Follow the steps below to create a new integration for Duo Security.

Step 1: Login to your Pia Partner Portal.

Step 2: Go to Configuration and navigate to the Integration menu option.

Step 3: In the Integration screen, click on the 'Custom Integration' button. This will give you option to create a new custom integration.

Step 4: In the New Integration screen, add the following details:

Tell us about your integration

  • Name: Type 'Duo Security' or a relevant name for Duo
  • Logo: Enter the logo for Duo
  • Category: Select a category. For this example, Communication Channel has been selected

How should Pia talk to the App / System?

  • Protocol: Select Rest API from the drop-down
  • Authentication Type: Select Bearer Auth with API Key from the drop-down
  • API Url: Select Fixed global base Url from the option
  • API Base Url: Add your Duo URL provided by Duo
  • Integration Fields
    • API Key: This is the API key provided by Duo
    • API Base Url: Add your Duo URL provided by Duo
    • Secret: Add a new Integration Value for Password. This will be the Secret for Duo

Integration Variables

  • Enable Client Configuration mode: Turn this toggle ON to save individual API key values for each of your clients. This is a must for Duo Integration setup as you need to use separate API Keys per client.
  • Enable integration variables to use them in your own custom automations: Keep this toggle ON so that you can use the integration variables in your custom automations
  • Integration Variable Prefix: Create a prefix to use in your variable. For the purpose of this example, "duo" is used

Integration Behaviour

  • Retry Behaviour on Server, Network and Auth Errors: This should be toggled ON
  • Automatic Retry Throttle Behaviour: This should be toggled ON

Step 5: Once the initial setup is done, click on "Save & Configure" to configure the integration for each of your clients.

Configuring Duo Security​

To configure Duo for each of your clients separately, follow the steps below:

  • Step 1: Clicking on "Save & Configure" in Step 5 will take you to the Configure Integration screen for Duo.

If you have just clicked on "Save", navigate to the Duo Security integration in the integration screen and click on Action>Configure.

  • Step 2: In the Configure Integration page, fill in the form field as below:

Configuration Fields

  • Set as Primary Configuration: If you have multiple configuration, you can select a single configuration as your primary config. For the purpose of this example, this will be left disabled.
  • Client: From the drop-down, select the client for whom you are configuring Duo.

Integration Fields

  • API Key: Fill the API Key provided for the client.
  • API Base URL: This section will be pre-filled based on the value provided while creating the integration
  • Secret: Add the Secret key provided by Duo for the client.

  • Step 3: Once done, Save your changes.

This completes Duo Integration configuration for the selected client.

Configuring Duo Automations​

Once the integration setup has completed, you will need to create a client tag for Duo in the Tags screen. To create a tag, follow the steps below:

Step 1: Go to the Tags screen in the Partner Portal

Step 2: Click on the 'New Tag' button

Step 3: Create a new tag called 'MFA: Cisco Duo'

Step 4: click Save

Step 5: Once the tag is created, apply the tag to your clients that are using the Duo Integration.

Once done, you will be able to see Duo automations in the Pia Chatbot for the clients that you have applied the tag to!

Configuring the Extension Points​

Note

Contact your PSM to get access to the Duo Integration (or via Partner Support).

The Challenge User Identity via Duo Extension can be used in built in automations as well as custom automations. Refer to the below for the required configurations.

  1. Navigate to the Pia Portal > Configuration > Clients > Select the appropriate package.

  2. Click 'here' under Extension Automation.

  3. Refer to the screenshot below for the extension point/s you wish to configure:

To learn more about configuring extensions, click here.